BBS Toolkit/BBS Toolkit.iso/programs/rompr110.zip/ROMPROC.DOC

Text File | 1993-04-28 | 27KB | 576 lines

    ┌────┐
    │──═─│
    │ ── │ ─────┐      ┌────┐             ROMProc Documentation File
    │    │   ROMProc   │──═─│                    Version 1.10
    │    │      └────> │ ── │          (c) Copyright 1993 - Stacy Smith
    │    │             │    │
    │    │             │    │
   ─┴────┴─           ─┴────┴─


                                Courtesy of:

                        The Bloom Beacon-Picayune BBS
          Node 1: [phone] (USRobotics Courier Dual Standard)
             Node 2: [phone] (USRobotics Courier V.32bis)
                             FidoNet 1:276/112
                                  Intelec
                             RoseNet (ID: BB-P)

                                Stacy Smith
                              Route 6 Box 189
                           Forest, Virginia 24551


┌────────────────────┐
│  1. Introduction:  │
└────────────────────┘

ROMProc is a BBS download file preprocessor designed to make optimal use of
CD-ROM and/or LAN BBS setups by copying the desired file(s) from the source
drive into a work directory, commenting them, transferring them to the remote
user with the desired protocol and cleaning up. ROMProc is different from other
programs in which it performs all these functions automatically from a single
program command.

By commenting files just prior to download, rather than commenting them when
posted, you will save a lot of disk space and your files will always have
up-to-date comments inserted. By stripping the comments from 200 megs of ZIP
files on my system, I gained about 2 megs of disk space!

ROMProc was developed primarily because I didn't like the current crop of
CD-ROM and server file handlers. They were either complicated to install,
didn't perform as desired, were designed as doors, memory hogs, ridiculously
expensive or crippled.


┌───────────────────────────┐
│  2. Features of ROMProc:  │
└───────────────────────────┘

      ∙ Handles the complete download process from a single command-line.
      ∙ Functions with any protocol, including single, batch and bi-directional
        protocols.
      ∙ May be installed in your BBS software as a batch file or a direct
        command-line.
      ∙ Automatically identifies ARC, ARJ, HYP, LZH, PAK, SQZ, ZIP and ZOO
        files, regardless of their file extensions (ideal for software
        distribution networks, like .SDN files), allowing commenting of these
        archivers that support archive comments (not all do).
      ∙ Automatically identifies ARJ, LZH, PAK, SQZ and ZIP self-extracting
        (SFX) archives.
      ∙ Comments all files prior to downloading, if desired.
      ∙ May be configured to insert a BBS ad file to the archives (ugh).
      ∙ Outputs sysop-configurable prompts to the user for indication of
        process status. ROMProc supports IRQs 2-7 with any base address as well
        as FOSSIL drivers.
      ∙ Fully multinode compatible.
      ∙ Windowed full-screen interface.
      ∙ User-selectable disk error logging.
      ∙ Not crippled.
      ∙ Returns the errorlevel of the transfer protocol, making ROMProc
        completely transparent to the BBS software.
      ∙ Written completely in C for optimal speed, using Microsoft C/C++ 7.0.
      ∙ Lifetime registration; pay ONCE and your registration number will work
        on all future versions!


┌─────────────────────────────────────────────────────────┐
│  3. Files Included in the ROMProc Distribution Archive  │
└─────────────────────────────────────────────────────────┘

        ROMPROC.EXE     CD-ROM Download File Processor program
        ROMPROC.CFG     Sample configuration file
        ROMPROC.DOC     This file
        HISTORY.TXT     ROMProc revision history in reverse order
        REGISTER.FRM    Registration form for ROMProc
        COMMENT.TXT     Sample comment file for inclusion in archives
        FILE_ID.DIZ     Internal description file

When you unzip the distribution archive, you should see my PKZIP authenticity
verification stamp, and a '-AV' after every file in the archive:

        # SSU301    The Bloom Beacon-Picayune BBS

If there are any files missing or added, or the -AV stamp is missing, the
archive has been tampered with. It would be advisable to call my BBS (listed at
the top of this document) for the latest version of ROMProc.


┌───────────────────────────┐
│  4. Program Requirements  │
└───────────────────────────┘

To the best of my knowledge, ROMProc will run on most any machine capable of
running a BBS package. My BBS setup is PCBoard 14.5a/10 running under DESQview
on a LANtastic 4.10 network, but other sysops that I have been in contact with
have successfully implemented ROMProc on a wide variety of hardware.

ROMProc requires DOS 3.x or later, as it uses DOS SHARE-compatible file reads
and writes.  ROMProc's memory requirements are very small (about 80K, plus
whatever memory is required to invoke the transfer protocols), therefore it can
be run in very low memory situations.

ROMProc has been developed and tested using the following archiving and
transfer protocols:

        ARJ 2.10 through 2.39 Beta 2 (by Robert Jung)
        LHA 2.13 (by Haruyasu Yoshizaki)
        PKZIP 1.10 through 2.04g (by PKWare)
        SQZ 1.08.2 (by Jonas Hammarberg)
        DSZ 11/06/92 (by Omen Technology)
        HS/Link 1.12 through 1.20 (by Sam Smith)


┌───────────────────┐
│  5. Registration  │
└───────────────────┘

ROMProc is not free; nor is ROMProc is crippled to force registration. ROMProc
is fully functional, and will always remain so. The only variation with the
registered copies is no time delay and beg message.

Why register? Besides a clean conscience, you will get a registration code that
will work for all future versions of ROMProc, and will remove the delay and
message displayed upon closing the door.

The registration fee for your unique code is $10 for non-commercial BBSs (not
too bad, eh?). The registration fee for commercial BBSs, defined if you run
your BBS in the course of a commercial business or for profit, is $20. Other
variations are available; refer to the file REGISTER.FRM for all registration
options. Please print the file REGISTER.FRM and fill it out. You can print out
the form by issuing the following command from the DOS prompt:

        TYPE REGISTER.FRM > PRN


┌───────────────────────────────────────┐
│  6. License, Warranty and Disclaimer  │
└───────────────────────────────────────┘

I'll keep this part short and sweet, and dispense with the legal-ese:

        License: You are allowed to use ROMProc for 30 days, after which you
           must either register ROMProc or stop using it completely. ROMProc
           registration is a license for your use of ROMProc; I retain
           ownership of the software. A single registration applies to a single
           BBS system, regardless of the number of computers used in the
           system. If you run two or more distinct BBS systems on the same
           computer(s) (with different names), you require two or more ROMProc
           registrations. Refer to the registration form for the currect
           pricing structure.

        Warranty: There isn't one. The only thing I'll guarantee is that
           ROMProc will take up disk space, and will disappear when deleted.

        Disclaimer: I'm not responsible for anything bad that happens. ROMProc
           works here, but I cannot be held responsible for it not working on
           your computer or doing any damage to hardware or software.

If these aren't agreeable with you, then the best thing to do is delete ROMProc
right now. I'll do my best to help any user (registered or not) that wants to
use ROMProc, and I'll act on bug reports quickly, but I simply cannot and will
not be responsible for anything bad, like lost data, disk crashes, or whatever
else you can think of.


┌───────────────────┐
│  7. Installation  │
└───────────────────┘

GENERAL INSTALLATION:
─────────────────────
Make a subdirectory on your hard drive. For the purposes of this document,
we'll call it "C:\ROMPROC". Unarchive the ROMProc distribution archive into
this subdirectory. You've more than likely already made it this far, if you're
reading this file. <grin>

The ROMProc system opens a few files simultaneously for various reasons. I
would recommend that you have a minimum of FILES=30 per node in your system
CONFIG.SYS file for a single-node system, since ROMProc is run in conjunction
with your BBS software.

If you are running under a network or a multitasking operating system, you
should already have DOS's SHARE.EXE loaded. You must have SHARE loaded in order
to take advantage of the file sharing and locking methods used by the ROMProc
program to prevent data loss. (If you are running a single-node system without
a multitasker, SHARE is not needed).

Edit the configuration file to suit your needs. Proper configuration will
require you to refer to this section, the previous section and the section
titled "Configuration", which has an in-depth explanation of each configuration
parameter and its function.

Note that for the ROMProc program, you can obtain a limited program syntax
screen simply by executing the program name "ROMPROC".

GENERIC INSTALLATION INTO YOUR BBS SOFTWARE:
────────────────────────────────────────────
The premise behind ROMProc is that instead of invoking your transfer protocol
as usual when sending files to remote, you invoke ROMProc instead. ROMProc will
copy all files the remote user requested, process them as configured and invoke
the desired protocol. Note that only the sending (remote download) protocol is
changed; the receiving (remote upload) procotol is not changed. Upon completion
of the transfer, ROMProc will return the errorlevel returned by the protocol,
ensuring ROMProc's transparency to the BBS software.

ROMProc must be run from the BBS node subdirectory; this is required to prevent
conflicts when multiple copies of ROMProc are run simultaneously. At the bare
minimum, three command-line parameters are required for ROMProc:

    c:\romproc\romproc -Cc:\romproc\romproc.cfg -Ffile.ext -Tz

where -C defines the full path and filename of the configuration file for
ROMProc and -F is the complete path and filename of the file (or batch list
file) to be sent to remote; this parameter is almost always passed by the BBS
software. Also, the required -T parameter defines to ROMProc which protocol to
invoke by letter.

When run in a multinode environment, you must also pass the BBS node number
(via the -N command-line switch) to prevent collisions during simultaneous
downloads (if no node number is defined, 0 is used by default):

    c:\romproc\romproc -Cc:\romproc\romproc.cfg -Ffile.ext -Tz -N2

In many installations, the node number is or can be defined as an environment
variable. For example, PCBoard sysops use the environment variable PCBNODE to
use in batch files for external utilities.

    c:\romproc\romproc -Cc:\romproc\romproc.cfg -Ffile.ext -Tz -N%PCBNODE%

All BBS software passes the port number and computer-to-modem speed (DTE), and
many also pass modem-to-modem carrier speed (DCE). These are passed on to
ROMProc via the -P, -S and -E command-line switches, respectively. BBS software
that supports bi-directional protocols will also pass the upload directory for
the protocol to place any unexpected uploads from remote. This is passed to
ROMProc using the -U command-line switch.

* NOTE: In order for ROMProc to send status information to the online user, you
        MUST define the -P and -S parameters. (The -P may be omitted from the
        command line in favor of the DSZPORT environment variable).

Most of the switches are self-explanatory. To be safe, if your BBS system
is capable of passing a parameter, pass it on to ROMProc using the appropriate
command-line switch. It can't hurt...

PCBOARD INSTALLATION:
─────────────────────
Installation in PCBoard is very easy. PCBoard uses two batch files for each
protocol, named PCBR?.BAT and PCBS?.BAT, where ? is the protocol letter. The
PCBR?.BAT (receive) batch files do not need to be changed for ROMProc, however,
the PCBS?.BAT batch file does. Below are sample Zmodem and HS/Link send (and
receive, for reference) batch files from my multinode system:

PCBSZ.BAT:
@Echo off
if exist pcberr.fil del pcberr.fil
if exist pcbdsz.log del pcbdsz.log
c:\romproc\romproc -Cc:\romproc\romproc.cfg -Tz -N%PCBNODE% -F%3 -P%1 -S%2 -E%5

PCBRZ.BAT:
@Echo off
if exist pcberr.fil del pcberr.fil
if exist pcbdsz.log del pcbdsz.log
dsz port %1 speed %2 ha cts est 0 %5 pB4096 pr1 rz %3

PCBSH.BAT:
@Echo off
if exist pcberr.fil del pcberr.fil
if exist pcbdsz.log del pcbdsz.log
c:\romproc\romproc -Cc:\romproc\romproc.cfg -Th -N%PCBNODE% -F%3 -P%1 -S%2 -E%5
    -U%6

PCBRH.BAT:
@Echo off
if exist pcberr.fil del pcberr.fil
if exist pcbdsz.log del pcbdsz.log
hslink -b%2 -p%1 -e%5 -u%6 -noc:\pcb\gen\dlpath.lst


With the exception of the -T parameter, all of your PCBS?.BAT files should be
identical; change the -T parameter to reflect the appropriate protocol letter.
For bi-directional protocols, such as HS/Link and BiModem, add the -U%6 command
switch.

If you wish full implementation of ROMProc, all protocols have to be shelled
instead of using the internal Xmodem and Ymodem protocols. Fortunately, DSZ is
capable of all variations of Xmodem and Ymodem as well as Zmodem. The following
is a screen snapshot of my PCBPROT.DAT file from PCBSETUP, with all protocols
running through ROMProc:

                       Port Lock
     Use Type Size MNP Open Lines             Protocol Description
     ═══ ════ ════ ═══ ════ ═════ ═══════════════════════════════════════
      A   I    128  N   N     N   ASCII (text files only)
      X   S    128  N   N     Y   Xmodem
      C   S    128  N   N     Y   Xmodem-CRC
      O   S   1024  N   N     Y   1K-Xmodem
      F   S   1024  Y   N     Y   1K-Xmodem/G
      Y   D   1024  N   N     Y   Ymodem    [Batch]
      G   D   1024  Y   N     Y   Ymodem/G  [Batch]
      Z   D   1024  N   N     Y   Zmodem    [Batch]
      M   D   1024  N   N     Y   Zmodem MobyTurbo  [Batch]
      H   B   2048  N   N     Y   HS/Link (bi-directional)  [Batch]
      N   I      0  N   N     N   None (ask each transfer)

Note the type for the Xmodem and Ymodem transfer protocols is now (S)helled or
(D)SZLOG batch, instead of (I)nternal.

OTHER BBS INSTALLATION:
───────────────────────

* NOTE: As my BBS is PCBoard, I have written the PCBoard-specific instructions.
        I would greatly appreciate some feedback from other BBS software users
        regarding ROMProc installation specifics.

APPLICATION NOTES:
──────────────────
PKZIP:
    PKZIP 2.04 uses direct-video output by default that will make the
    processing window look rather ugly when executed. To remedy this, set the
    PKNOFASTCHAR environment variable which will revert PKZIP 2.04 to the older
    1.10-style video output. (It doesn't matter what your set the variable to,
    PKZIP just looks for its existence).

SQZ:
    SQZ also uses direct-video output, but unlike PKZIP 2.04, it cannot be
    defeated. The processing window may look odd, but rest assured it is
    operating correctly.

DSZ:
    In many cases, the use of DSZPORT environment variable is more desirable
    than passing the COM port information. This allows easier definition of
    non-standard COM ports addresses. For example, if you are using COM2 for a
    BBS node, add:

            SET DSZPORT=2

    to your node batch file. If you are running a non-standard COM port, define
    the base address and IRQ on the command line. For example, if COM3 (a
    non-standard port for IBM PCs) is used with 3e8 is the base address and 5
    is the assigned IRQ, the setting would be:

            SET DSZPORT=3e8,5

    If you elect to use the DSZPORT environment variable, it is no longer
    necessary to pass the -P command-line switch or to add the "port @PORT@"
    parameter to the DSZ command lines for Xmodem, Ymodem, and Zmodem transfers
    in the ROMProc configuration file.

    In addition, ROMProc will search the environment for the DSZPORT variable
    and use it for the com port definitions for it's user status output.

HS/Link:
    The HS/Link command-line can include the -NF switch to turn off HS/Link's
    full-screen display, allowing it to run in ROMProc's transfer protocol
    window. Otherwise, ROMProc's local display will be overwritten by HS/Link's
    display.


┌────────────────────┐
│  8. Configuration  │
└────────────────────┘

The sample configuration file included in the distribution archive is heavily
commented, but some additional information is provided below:

GENERAL PARAMETERS:
───────────────────
REG_CODE
    The registration code EXACTLY as provided to you on your registration
    letter. If this is an unregistered version, comment out this line. Note
    that this is case-sensitive, as the serial number, BBS name and sysop name
    are all encrypted into this code.

BBS_NAME
    The BBS name EXACTLY as provided to you on your registration letter. If
    this is an unregistered version, comment out this lines. Note that this is
    case-sensitive!

SYSOP_NAME
    The sysop name EXACTLY as provided to you on your registration letter. If
    this is an unregistered version, comment out this line. You get the picture
    by now...

WORK_DIR
    The full path for the specific subdirectory for ROMProc to store file(s) to
    be downloaded. This must include the trailing backslash! If this directory
    does not exist at runtime, ROMProc will attempt to create it. This can be
    set to a RAM disk for greater speed, since ROMProc will detect an out of
    disk space condition and allow the download to continue from the original
    file.

DISK_BUFFER
    The size of the disk I/O buffer you wish to allocate in bytes (valid values
    are between 2048 bytes and 16384 bytes). Optimal performance is obtained
    with a value that is a multiple of 2048 bytes, since this is the size of a
    typical hard disk cluster. 4096 seems to be a good number for me, although
    a larger size will improve performance somewhat. If you find yourself
    running out of memory when executing archivers or protocols, reduce this
    number to increase your available memory. If no value is specified, the
    disk buffer will default to 4096 bytes.

LOG_FILE
    The complete path and filename of the log file for ROMProc to record
    errors. Comment the line out if you don't want any disk error logging.

LOCK_LINES
    If you want ROMProc to preserve three lines at the top or bottom of the
    local display, enter TOP or BOTTOM as desired, otherwise, enter NONE or
    comment the line out.

BBS_AD_FILE
    The directory path and filename for your BBS ad to be inserted into each
    and every archive processed by ROMProc. Note that you must provide a path,
    or it will not be copied. I STRONGLY recommend against them; BBS ads are
    aggravating to other sysops, so please be considerate and use the archive
    comment instead. BBS ad files are the scourge of the BBS world. This
    parameter is commented out by default.

COMMENT_ARC
    If you want ROMProc to comment archives (if supported by the archive
    format) enter YES. If not, enter NO or comment the line out. This is much
    more desirable than inserting BBS ads.

PROC_DRIVE
    Specify the drive letters for file preprocessing (BBS ad insertion and/or
    commenting). Any file requested from a non-specified drive will still be
    tranmitted (unmodified) from the original location. This allows
    preprocessing of certain drives (e.g. CD-ROMs), but not all. Drives may be
    specified in ranges, seperated by a hyphen, and/or individual drives may be
    seperated by spaces, commas or semi-colons. The following examples are all
    valid, and will select drives letters C through J:
        PROC_DRIVE C-J
        PROC_DRIVE C D E F G H I J
        PROC_DRIVE C-F G H-J
        PROC_DRIVE C-F,G-I,J

COMMUNICATION DEFINITIONS:
──────────────────────────
COMM_IO
    If you want ROMProc to output status information to the user on-line, enter
    YES; if you do not want ROMProc to output information, enter NO or comment
    the line out. Note that the -P and -S command line switches must be passed
    for user status information to be generated by ROMProc.

PROC_PROMPT
    This line of text will be displayed to the user upon the start of download
    file processing. It should be used to inform the user that it may take a
    few moments to get the files ready.

DL_PROMPT
    This line of text will be displayed to the user upon the start of the
    transfer protocol. It should be used to inform the user to start the
    download on their end.

ARCHIVER DEFINITIONS:
─────────────────────
Each archiver, is denoted by ARCHIVER x, where x is a sequential number. Up to
10 archivers can be executed by ROMproc. ROMProc is capable of automatically
detecting ARC, ARJ, HYP, LZH, PAK, SQZ, ZIP and ZOO archives. The next 4
keywords are required after the ARCHIVER statement; do not comment any of them
out or insert other parameters or comments between them. I would also advise
against changing the command options I have set, unless you have need to do so.
Any other archiver can be added, if desired; the only requirement is that the
archiver must return a DOS errorlevel so that ULP can determine if it ran
properly. If you do not explicitly define the path to your archiver(s), it must
in a directory included in the DOS PATH environment variable.
    ARCHIVER    = denotes a new archiver definition.
    ARC_EXT     = the extension for this particular archiving format.
    ARC_ADD     = the command line to add files to an archive, including all
                  command-line switches desired. Place the variable @ARCHIVE@
                  where the filename is to be inserted in the command line and
                  @FILE@ where the filespec is to be inserted.
    ARC_COMMENT = the command line to comment archives, including all command-
                  line switches desired. Place the variable @ARCHIVE@ where the
                  filename is to be inserted in the command line. If the
                  archive utility does not support commenting, leave this line
                  blank.
    ARC_ERR     = the errorlevel that the archiver returns upon success. This
                  information should be available in the program's
                  documentation.

PROTOCOL DEFINITIONS:
─────────────────────
Each protocol, is denoted by PROTOCOL x, where x is the letter designating the
protocol. Up to 15 protocols can be executed by ROMproc. The next keyword is
required after the PROTOCOL statement; do not comment it out or insert other
parameters or comments between them. I have configured most of the popular
protocols, using the PCBoard default lettering scheme. If you do not explicitly
define the path to your archiver(s), it must in a directory included in the DOS
PATH environment variable.
    PROTOCOL    = denotes a new protocol definition
    PROT_SEND   = the command line to transmit the file(s) to remote, including
                  all command-line switches desired. Place the following
                  variables as needed for ROMProc to properly invoke the
                  protocol.
                  @PORT@     COM port to be used by the protocol
                  @SPEED@    COM port computer-to-modem speed (DTE)
                  @CARRIER@  modem-to-modem carrier speed (DCE)
                  @FILE@     File (or batch list file) to be downloaded
                  @ULDIR@    path to upload directory for bi-directional
                             protocols.


┌──────────────┐
│  9. Support  │
└──────────────┘

If you require support for ROMProc, I can be contacted by any of the following
means:

    ∙ Fidonet netmail (node:  1:276/112)
    ∙ Intelec BBS Doors conferences
    ∙ RoseNet routed mail (system ID:  BB-P)
    ∙ The ULP Support conference (#42) on Salt Air (PCBoard support BBS)
    ∙ The Support conference (#2) on my BBS (listed at the top of this
      document).


┌─────────────────────────────┐
│  10. The Future of ROMProc  │
└─────────────────────────────┘

ROMProc will be supported as long as I'm in the BBSing business (which will be
quite a while...once it's in your blood, you can never shake it <g>). The
ROMProc system will be continually expanding it's features, so get your
comments in now! Some current plans:

      ∙ Add code enabling ROMProc to output status information to the remote
        user for long batch processing on slow systems.
      ∙ Any ideas from you guys? Thanks! <g>

If you have any other suggestions, contact me by U.S. snail-mail or on my BBS
at the number at the top of this document.

Thanks for giving ROMProc a try!


┌────────────────────────────────┐
│  Appendix A:  DOS Errorlevels  │
└────────────────────────────────┘

The following is a list of the errorlevels than can be returned by ROMProc. The
reason the successful execution errorlevel may not be zero is because ROMProc,
upon error-free completion, returns the errorlevel of protocol, which makes
ROMProc completely transparent to the BBS software.

        0           Successful execution (usually, depends on the protocol)
        99          Help screen (executing a program with no or an
                        insufficient number of arguments)
        100         Could not close all open files
        101         Invalid command-line parameter
        102         Configuration file not found
        103         No download file (or batch list file) specified
        104         No transfer protocol specified
        108         Invalid configuration file format (archiver definitions)
        109         Invalid configuration file format (protocol definitions)
        110         Unable to allocate heap memory
        112         Invalid registration code
        117         Invalid node number
        120         Archiver BBS advertisement insertion error
        121         Archiver commenting error
        125         Communication system for online status failure
        200         Undefined error (internal to ROMProc program)